home *** CD-ROM | disk | FTP | other *** search
/ Amiga Plus 2002 #11 / Amiga Plus CD - 2002 - No. 11.iso / Tools / AmigaSystem / Scalos / PreferencesLib / doc / preferences.doc
Encoding:
Text File  |  2002-10-28  |  15.8 KB  |  468 lines
  1. preferences.library/--background--            preferences.library/--background--
  2.  
  3.    PURPOSE
  4.       The preferences.library provides a convenient way to store the
  5.       preferences for your program. All internal management and I/O of your
  6.       data is handled by the library, and is controlled via a simple interface
  7.       which makes use of identifiers and tags to access the data. Multiple
  8.       programs can access the data (held only once in memory) at the same time
  9.       as access is arbitrated through the use of semaphores.
  10.  
  11.    OVERVIEW
  12.       Most of the data and structures mentioned here will be unavailable to
  13.       the programmer, but it is useful to know, so that the correct use of the
  14.       library can be adhered to.
  15.  
  16.       * All accesses to a preferences structure must be made through a
  17.         "PrefsHandle". A PrefsHandle is accessed by name (maximum of 32
  18.         unique characters) using AllocPrefsHandle(). Within a PrefsHandle a
  19.         list of ID's within this handle is stored. The pointer remains valid
  20.         until you call FreePrefsHandle().
  21.  
  22.       * The ID's are the first level of separation of preference data. Each
  23.         ID must be 4 ASCII characters, for example "MAIN", or "MENU". For
  24.         creating the ID you can use the MAKE_ID macro as defined in
  25.         libraries/iffparse.h. ID's are unique within each PrefsHandle. This
  26.         means that you can have an ID "MAIN" within two PrefsHandle's
  27.         and they will be completely different ID's.
  28.  
  29.       * The second level of separating the data is to use tags. A tag can have
  30.         any value except 0. The data is stored along with the tag. Tags are
  31.         unique within an ID the same way an ID is unique within a PrefsHandle.
  32.  
  33.       This gives the following structure to preferences items:
  34.  
  35.                        Main list of all preferences handles
  36.                                /        |       \
  37.                 ______________/         |        \___________________
  38.                /                        |                            \
  39.           PrefsHandle              PrefsHandle      ...          PrefsHandle
  40.         _/          \_
  41.        /              \
  42.       ID        ______ID
  43.     _/ |\      /   __/ |\
  44.    /   | \    |   /   /  \         etc.
  45.   Tag+ | Tag+ | Tag+ | Tag+
  46.   Data | Data | Data | Data
  47.        |      |      |
  48.      Tag+   Tag+   Tag+
  49.      Data   Data   Data
  50.  
  51.  
  52.       The data can be manipulated in these structures using SetPreferences()
  53.       to set the data and GetPreferences() to retrieve the data.
  54.  
  55.  
  56.       There is an alternative way to store the data. You can also have a list
  57.       of data items for each tag value. NB: you cannot mix normal single data
  58.       tags and their functions with the list type tags and their functions.
  59.       This is achieved using SetEntry(), GetEntry() and RemEntry() functions.
  60.       Each data item in the list is accessed using a logical entry number.
  61.       Since the data items are not explicitly accessed using this entry
  62.       number (such as with an array), their positions can change when you add
  63.       items in the middle of the list. For this reason you cannot guarantee
  64.       the order of data items in this sub-list. Applications of this method of
  65.       storing data could be a list of files which your program runs at
  66.       startup, without needing them to be in any specific order.
  67.  
  68.  
  69.       FindPreferences() will return a pointer to the tag specified and can be
  70.       used to find whether a certain tag exists or to access the data (if you
  71.       know the internal structure of tag items :). This works for either
  72.       type of tag (single data item or list of data items).
  73.  
  74.       ReadPrefsHandle() and WritePrefsHandle() can be used to read or write an
  75.       entire PrefsHandle in the specified file.
  76.  
  77. preferences.library/AllocPrefsHandle        preferences.library/AllocPrefsHandle
  78.  
  79.    NAME
  80.       AllocPrefsHandle -- Allocate preferences handle
  81.  
  82.    SYNOPSIS
  83.       prefshandle = AllocPrefsHandle( name )
  84.       D0                             A0
  85.  
  86.       APTR AllocPrefsHandle( STRPTR );
  87.  
  88.    FUNCTION
  89.       Allocate a handle so that the preferences inside can be accessed. All
  90.       successful calls to this function must be matched by a call to the
  91.       FreePrefsHandle() function.
  92.  
  93.    INPUTS
  94.       name - a string that you can identify the preferences set by
  95.  
  96.    RESULT
  97.       prefshandle - a pointer to the newly allocated preferences set or NULL
  98.                     for failure.
  99.  
  100.    EXAMPLE
  101.  
  102.    NOTES
  103.  
  104.    BUGS
  105.  
  106.    SEE ALSO
  107.       FreePrefsHandle()
  108.  
  109. preferences.library/FindPreferences          preferences.library/FindPreferences
  110.  
  111.    NAME
  112.       FindPreferences -- get pointer to data stored for a preference tag
  113.  
  114.    SYNOPSIS
  115.       prefsstruct = FindPreferences(prefshandle, ID, Tag);
  116.       D0                            A0           D0  D1
  117.  
  118.       struct PrefsStruct *FindPreferences(APTR, ULONG, ULONG);
  119.  
  120.    FUNCTION
  121.       Searchs for the preferences entry specified by the preferences handle,
  122.       ID and Tag values and returns a pointer to whatever is stored there.
  123.       Similar to GetPreferences() and GetEntry(), but since it does not copy
  124.       any data can be used on both types of tag it can be used to find out
  125.       whether a tag is present in a PrefsHandle.
  126.  
  127.    INPUTS
  128.       PrefsHandle   - pointer to a previously successfully allocated
  129.                       preferences handle
  130.       ID            - id of the set within the preferences handle you wish to
  131.                       use
  132.       Tag           - the tag used to identify this preference data within the
  133.                       the ID set
  134.  
  135.    RESULT
  136.       prefsstruct - pointer to the preferences item if found, NULL otherwise
  137.  
  138.    EXAMPLE
  139.  
  140.    NOTES
  141.       The returned pointer will return a pointer to the tag item, which will
  142.       either be followed by the data (if set with SetPreferences()) or the
  143.       list of sub items (if set by SetEntry()).
  144.  
  145.    BUGS
  146.  
  147.    SEE ALSO
  148.       AllocPrefsHandle(), SetPreferences(), SetEntry(), GetPreferences(),
  149.       GetEntry()
  150.  
  151. preferences.library/FreePrefsHandle          preferences.library/FreePrefsHandle
  152.  
  153.    NAME
  154.       FreePrefsHandle -- free a previously allocated preferences handle
  155.  
  156.    SYNOPSIS
  157.       FreePrefsHandle(PrefsHandle);
  158.                       A0
  159.  
  160.       void FreePrefsHandle(APTR);
  161.  
  162.    FUNCTION
  163.       Frees the preferences set associated with the handle passed into this
  164.       function. This handle can ONLY be created by calling AllocPrefsHandle
  165.       successfully. You MUST NOT use this preferences handle after you free
  166.       it.
  167.  
  168.    INPUTS
  169.       PrefsHandle - pointer to the preferences handle successfully allocated
  170.                     using AllocPrefsHandle()
  171.  
  172.    RESULT
  173.  
  174.    EXAMPLE
  175.  
  176.    NOTES
  177.  
  178.    BUGS
  179.  
  180.    SEE ALSO
  181.       AllocPrefsHandle()
  182.  
  183. preferences.library/GetEntry                        preferences.library/GetEntry
  184.  
  185.    NAME
  186.       GetEntry -- fills in a user structure from a preferences item
  187.  
  188.    SYNOPSIS
  189.       bytescopied = GetEntry(PrefsHandle, ID, Tag, Struct, Struct_Size, Entry)
  190.       D0                     A0           D0  D1   A1      D2           D3
  191.  
  192.       ULONG GetEntry(APTR, ULONG, ULONG, APTR, UWORD, ULONG);
  193.  
  194.    FUNCTION
  195.       Copies the data stored in a preferences item to a struture or area of
  196.       memory supplied by the programmer. The preference item will come from
  197.       the list item at position "Entry" from the list in the Tag / ID /
  198.       preferences handle.
  199.  
  200.    INPUTS
  201.       PrefsHandle   - pointer to a previously successfully allocated
  202.                       preferences handle
  203.       ID            - id of the set within the preferences handle you wish to
  204.                       use
  205.       Tag           - the tag used to identify this preference data within the
  206.                       the ID set
  207.       Struct        - pointer to the structure/memory you wish to copy the
  208.                       preferences data to
  209.       Struct_Size   - size of the structure/memory
  210.       Entry         - the position in the Tag's entry list to read this data
  211.                       from
  212.  
  213.    RESULT
  214.       bytescopied - the actual number of bytes copied from the preference data
  215.                     to the structure/memory pointer.
  216.  
  217.    EXAMPLE
  218.  
  219.    NOTES
  220.       DO NOT MIX this command with Tag's which have had their preference data
  221.       set with SetPreferences. They are different internally. Only use this
  222.       with Tag's used with SetEntry.
  223.  
  224.    BUGS
  225.  
  226.    SEE ALSO
  227.       AllocPrefsHandle(), SetPreferences(), SetEntry()
  228.  
  229. preferences.library/GetPreferences            preferences.library/GetPreferences
  230.  
  231.    NAME
  232.       GetPreferences -- returns data from a preference item to the programmer
  233.  
  234.    SYNOPSIS
  235.       bytescopied = GetPreferences(PrefsHandle, ID, Tag, Struct, Struct_Size);
  236.       D0                           A0           D0  D1   A1      D2
  237.  
  238.       ULONG GetPreferences(APTR, ULONG, ULONG, APTR, UWORD);
  239.  
  240.    FUNCTION
  241.       Copies the data stored in a preferences item (as referenced the prefs
  242.       handle, ID and Tag values) into a structure/memory that the user passes.
  243.       The number of bytes actually copied will be returned.
  244.  
  245.    INPUTS
  246.       PrefsHandle   - pointer to a previously successfully allocated
  247.                       preferences handle
  248.       ID            - id of the set within the preferences handle you wish to
  249.                       use
  250.       Tag           - the tag used to identify this preference data within the
  251.                       the ID set
  252.       Struct        - pointer to the structure/memory you wish to store
  253.       Struct_Size   - size of the structure/memory
  254.  
  255.    RESULT
  256.  
  257.    EXAMPLE
  258.  
  259.    NOTES
  260.       This function does nothing if the ID and Tag values are 0, as they are
  261.       not considered valid as an ID or a Tag.
  262.  
  263.       This function assumes a single preferences item per tag, DO NOT USE IT
  264.       with preferences items set up with the "Entry" functions.
  265.  
  266.    BUGS
  267.  
  268.    SEE ALSO
  269.       AllocPrefsHandle(), SetPreferences()
  270.  
  271. preferences.library/ReadPrefsHandle          preferences.library/ReadPrefsHandle
  272.  
  273.    NAME
  274.       ReadPrefsHandle -- Load an entire prefs handle from disk
  275.  
  276.    SYNOPSIS
  277.       ReadPrefsHandle(PrefsHandle, Filename);
  278.                       A0           A1
  279.  
  280.       void ReadPrefsHandle(APTR, STRPTR);
  281.  
  282.    FUNCTION
  283.       Attempts to read data from a file on disk (previously saved with
  284.       WritePrefsHandle) into the specified preferences handle.
  285.  
  286.    INPUTS
  287.       PrefsHandle   - pointer to a previously allocated preferences handle
  288.       Filename      - full path and name of file to load from
  289.  
  290.    RESULT
  291.  
  292.    EXAMPLE
  293.  
  294.    NOTES
  295.       Data is stored in memory using SetPreferences() and SetEntry()
  296.       functions.
  297.  
  298.    BUGS
  299.       Should probably return a value to indicate whether file was read
  300.       successfully or not.
  301.  
  302.    SEE ALSO
  303.       AllocPrefsHandle(), WritePrefsHandle(), SetPreferences(), SetEntry()
  304.  
  305. preferences.library/RemEntry                        preferences.library/RemEntry
  306.  
  307.    NAME
  308.       RemEntry -- remove an preferences item entry from a Tag that has a list
  309.  
  310.    SYNOPSIS
  311.       success = RemEntry(PrefsHandle, ID, Tag, Entry);
  312.       D0                 A0           D0  D1   D2
  313.  
  314.       ULONG RemEntry(APTR, ULONG, ULONG, ULONG);
  315.  
  316.    FUNCTION
  317.       Removes a preferences item, that is in a list at position "Entry", at
  318.       the given preferences handle, ID and Tag locations.
  319.  
  320.    INPUTS
  321.       PrefsHandle   - pointer to a previously successfully allocated
  322.                       preferences handle
  323.       ID            - id of the set within the preferences handle you wish to
  324.                       use
  325.       Tag           - the tag used to identify this preference data within the
  326.                       the ID set
  327.       Entry         - the position in the Tag's entry list to read this data
  328.                       from
  329.  
  330.    RESULT
  331.       success - whether the entry was successfully removed or not.
  332.  
  333.    EXAMPLE
  334.  
  335.    NOTES
  336.       DO NOT MIX this function with Tag's which have been created with
  337.       SetPreferences.
  338.  
  339.    BUGS
  340.  
  341.    SEE ALSO
  342.       AllocPrefsHandle(), SetPreferences(), SetEntry()
  343.  
  344. preferences.library/SetEntry                        preferences.library/SetEntry
  345.  
  346.    NAME
  347.       SetEntry -- adds preference data to a list of entries related to the Tag
  348.  
  349.    SYNOPSIS
  350.       SetEntry(PrefsHandle, ID, Tag, Struct, Struct_Size, Entry)
  351.                A0           D0  D1   A1      D2           D3
  352.  
  353.       void SetEntry(APTR, ULONG, ULONG, APTR, UWORD, ULONG);
  354.  
  355.    FUNCTION
  356.       Stores some user data in the preferences item in the preferences handle,
  357.       under the specified ID and Tag values. It will be stored at position
  358.       "Entry" in a list of values being stored under the given Tag value.
  359.  
  360.    INPUTS
  361.       PrefsHandle   - pointer to a previously successfully allocated
  362.                       preferences handle
  363.       ID            - id of the set within the preferences handle you wish to
  364.                       use
  365.       Tag           - the tag used to identify this preference data within the
  366.                       the ID set
  367.       Struct        - pointer to the structure/memory you wish to store
  368.       Struct_Size   - size of the structure/memory
  369.       Entry         - the position in the Tag's entry list to store this data
  370.  
  371.    RESULT
  372.  
  373.    EXAMPLE
  374.  
  375.    NOTES
  376.       DO NOT MIX this command with Tag values which have been created with
  377.       SetPreferences. They are different internally. If you have previously
  378.       stored data in this PrefsHandle/ID/Tag/Entry combination, it will be
  379.       overwritten if the data sizes are the same, otherwise this new data will
  380.       be inserted at the position specified.
  381.  
  382.    BUGS
  383.       Since the entry can be added at the end of the list (if the position is
  384.       not found), this means that it can be added at a position not equal to
  385.       the given Entry value. This is not a bug as such, but the function
  386.       should probably return the actual position that it is inserted at. Also,
  387.       the function can fail (when allocating memory) so it should also return
  388.       a value to indicate that failure.
  389.  
  390.    SEE ALSO
  391.       AllocPrefsHandle(), SetPreferences()
  392.  
  393. preferences.library/SetPreferences            preferences.library/SetPreferences
  394.  
  395.    NAME
  396.       SetPreferences -- store data in a preference item
  397.  
  398.    SYNOPSIS
  399.       SetPreferences(PrefsHandle, ID, Tag, Struct, Struct_Size);
  400.                      A0,          D0, D1,  A1,     D2
  401.  
  402.       void SetPreferences(APTR, ULONG, ULONG, APTR, UWORD);
  403.  
  404.    FUNCTION
  405.       Stores a structure of data in the preferences handle, under the given
  406.       ID and tag values.
  407.  
  408.    INPUTS
  409.       PrefsHandle   - pointer to a previously successfully allocated
  410.                       preferences handle
  411.       ID            - id of the set within the preferences handle you wish to
  412.                       use
  413.       Tag           - the tag used to identify this preference data within the
  414.                       the ID set
  415.       Struct        - pointer to the structure/memory you wish to store
  416.       Struct_Size   - size of the structure/memory
  417.  
  418.    RESULT
  419.  
  420.    EXAMPLE
  421.  
  422.    NOTES
  423.       This function does nothing if the ID and Tag values are 0, as they are
  424.       not considered valid as an ID or a Tag. This will overwrite any data
  425.       that has previously been stored in this PrefsHandle/ID/Tag combination.
  426.  
  427.       This sets up a single preferences item for the given tag. DO NOT MIX
  428.       preferences created with this function with the "Entry" commands!!!
  429.  
  430.    BUGS
  431.  
  432.    SEE ALSO
  433.       AllocPrefsHandle()
  434.  
  435. preferences.library/WritePrefsHandle        preferences.library/WritePrefsHandle
  436.  
  437.    NAME
  438.       WritePrefsHandle -- saves an entire preferences handle to a file
  439.  
  440.    SYNOPSIS
  441.       WritePrefsHandle(PrefsHandle, Filename);
  442.                        A0           A1
  443.  
  444.       void WritePrefsHandle(APTR, STRPTR);
  445.  
  446.    FUNCTION
  447.       Stores all the data and structure of the preferences handle to a file
  448.       on disk.
  449.  
  450.    INPUTS
  451.       PrefsHandle - pointer to a previously allocated preferences handle
  452.       Filename    - full path and name of file to save to
  453.  
  454.    RESULT
  455.  
  456.    EXAMPLE
  457.  
  458.    NOTES
  459.       This function can deal with single or list entries for a Tag value.
  460.  
  461.    BUGS
  462.       Should probably return a value to show if the file was successfully
  463.       saved or not.
  464.  
  465.    SEE ALSO
  466.       AllocPrefsHandle(), ReadPrefsHandle()
  467.  
  468.